Night Owl 6/Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso/015a/pko10j.zip/PKO.DOC

Text File | 1991-08-11 | 19KB | 479 lines

   Palindrome KickOff! manual
   (C) Copyright Darryl G. Whitmore 1990, 1991.  All Rights Reserved.


    1.00 Introduction

   Hello!  I'm Darryl G. Whitmore, and I work as a programmer for the
   Palindrome Corporation, maker of The Network Archivist (TNA).  During
   my free time, I like to work on software utilities, and Palindrome
   KickOff! (PKO) is one of my little projects.

   PKO is a utility designed for doing secure, unattended backup
   (preferrably using TNA!).  Credit for the idea goes to TNA user Joe
   Swenn.  He was concerned about doing unattended overnight backup
   because the workstation running TNA must be left logged in with with
   supervisor equivalence (this was in the TNA 1.x days; TNA 2.0 has a
   secure Auto-Login feature). He wrote a program (in ZBASIC, I think)
   that would execute TNA at the desired time.  You couldn't "get out"
   of this program (and thus have access to the workstation and the LAN)
   unless you knew the right password.  The only other way to stop the
   program was to reboot the workstation, and in doing so, the
   supervisor equivalence is lost.  I thought that this was a great
   idea, and decided to see if I could write such a program.  PKO is
   what I came up with!

    2.00 Installation & Upgrading

   The PKO package is distributed in a ZIP file (PKOnnn.ZIP, where nnn =
   the version).  The package consists of:

      PKO.EXE        PKO itself
      PKO.DOC        PKO's manual
      VERSION.DOC    PKO's version history ("what's new")
      REGISTER.DOC   PKO's registration form

   To install PKO, simply copy PKO.EXE and its associated documentation
   files (*.DOC) into any directory present in your PATH (any directory
   that has a search mapping "pointing" to it).  I suggest putting PKO
   in the directory where TNA's executables (.EXE files) are located
   (usually \TNA).

   If you're upgrading from an earlier version of PKO, the upgrade
   process is the same: simply copy the new PKO files into the directory
   where your existing version of PKO resides.  Your existing PKO
   configuration and log files will be safe; the format of these files
   has not changed.

    3.00 Syntax

   PKO will display its syntax if you simply execute:

      PKO

   It will also display the syntax if invalid command line arguments are
   entered.  Here is the syntax:

      PKO mode

      modes:

       /M             Run PKO in Menu Mode
       /W [switches]  Run PKO in Wait Mode

       switches:
         /OThh:mm     Override kickoff time
         /OCcommand   Override kickoff command

    4.00 Quick start

   To get going with PKO ASAP, here is a quick start.  Once you have PKO
   working and have the general idea, you can refer back to the more detailed
   tutorial that follows.

   First, install PKO as detailed above (in 2.00).  Next, enter the following
   command:

      PKO /M

   PKO will ask you for a password, and once you've given it one, select
   "Change KickOff options..." from the main menu.  Proceed to enter a
   kickoff command and time.  For your quick start kickoff command, you might
   choose something like: "TNA2TAPE /A /Q".  For the kickoff time, enter the
   time that it will be in about 5 minutes (use 24 hour format).  After
   you've configured PKO for kickoff, press ESC from the main menu to return
   to DOS.

   Now that you've configured PKO, execute the following command to start it
   up:

      PKO /W

   PKO will now wait around until kickoff time, which should be in about 5
   minutes.  During this time, you won't be able to "break" out of PKO,
   either with CTRL-C or CTRL-BREAK.  The only way to stop PKO is to press
   ESC and when prompted, provide your password.

   Watch PKO tick off the time, and then, at kickoff time, it will execute
   the kickoff command.

    5.00 Tutorial

   One more time, then, here is a detailed tutorial on how to setup and use
   PKO.

    5.10 Configuration

   PKO needs to know what command you want to execute, what time you
   want to execute it, and what your password will be.  To configure PKO
   with this information, run PKO in "Menu Mode" by entering the
   following command at the DOS prompt:

      PKO /M

   PKO will first ask you to enter and verify your password.  You
   have 20 characters for your password, and can use just about any word
   or sentence.  Don't forget your password!

   Once past the password barrier, select "Change KickOff options..."
   from the main menu to enter your configuration:


   The "Command" is the command that you want PKO to execute.  It
   can be any valid DOS command, a program or a batch file.

   The "Time" is the time that you want PKO to execute your command.
   You enter the time in 24 hour format: 22:30 is equal to 10:30pm.  The
   exception is midnight, which is entered as 00:00 (just as it is with
   the DOS TIME command).

   Once you have configured PKO, select "Exit to DOS" from the main
   menu to return to DOS.  If you take a look in the directory where
   you've installed PKO, you'll find a new file: PKO.CFG.  This is where
   PKO keeps your configuration information.  For security, it is
   encrypted.

    5.20 Running PKO

   To have PKO "kickoff" your command, run it in "Wait Mode" by
   entering the following command at the DOS prompt:

      PKO /W

   You'll see PKO's Wait Mode status box, which displays the current
   date and time, as well as the kickoff command and time, and a
   countdown to the kickoff.  Each minute, the status box will change
   positions, or bounce (I call it the "bouncing box").  This is so that
   the status box doesn't burn its image into your monitor.  This
   bouncing is random and will occur every minute; I kind of like to
   just sit and watch it (but then, I spend my free time writing little
   utilities like this).

   To suspend Wait Mode and return to DOS, press ESC at any time.
   PKO will then give you 10 seconds to input your password.  If you
   take longer than 10 seconds, or input an incorrect password, wait
   mode will resume.

   When kickoff time arrives, PKO will "stuff" your command into the
   keyboard buffer (along with a carriage return) and return to DOS.
   DOS will then look for the next sequence of keystrokes in the buffer,
   and process them.  The effect is the same as if you had waited at your
   machine until kickoff time and then typed in the command yourself. It's
   important to note that PKO, unlike a terminate & stay resident (TSR)
   program, doesn't remain in memory when it runs your command; your
   command has the benefit of having access to all available free RAM.

    5.30 Additional security

   PKO does a good job of kicking off your command at the appointed time
   and keeping the workstation secure during Wait Mode, but you'll need
   to do a little more work to have a truly seamless, secure unattended
   backup.  To do this, you'll typically configure PKO to execute a
   batch file.  For example, let's call the batch file BACKUP.BAT.
   Here's what it looks like:

      TNA2TAPE /A /Q
      PKO /W

   PKO kicks off BACKUP.BAT, which runs a TNA automatic archive in
   quiet mode.  When this is done, the batch file re-runs PKO in Wait

   Mode.  This method insures that the workstation is secure after the
   backup, as well as before.  This version of BACKUP.BAT accomplishes
   the same thing:

      TNA2TAPE /A /Q
      LOGOUT

   One final note: you'll need to make sure that no one can tamper with
   BACKUP.BAT; it wouldn't be difficult to compromise your security by
   modifying the batch file that PKO executes!  I'd suggest putting it
   in a subdirectory that is only "visible" to the supervisor.

    5.40 The PKO log file.

   PKO maintains a log when it is in Wait Mode.  The log file is called
   PKO.LOG, and will be found in the directory where you've installed
   PKO.  It is a simple ASCII file, and may be viewed with any word
   processor or editor.  PKO makes log entries when "interesting" events
   occur, such as:

      - When Wait Mode begins, ends, and is suspended
      - When invalid passwords are entered during Wait Mode
      - When errors occur
      - On the hour & half hour

   You'll probably want to review PKO's log regularly.  It is generally
   quite boring, but may some day alert you to the fact that an intruder
   tried to suspend Wait Mode by trying several bad passwords.

   Over time, the log file will grow in size.  You may delete it (or edit
   it to remove old entries) at any time.

    5.50 Running PKO with command line overrides.

   For added flexibility, you may override PKO's configured kickoff time
   and command.  This is done via optional command line switches that
   are used in conjunction with the Wait Mode command line switch (/W).
   Both command line overrides may be used together.

    5.51 Overriding the kickoff time

   The configured kickoff time may be overridden with the /OT switch.
   This switch requires a parameter: the override time itself.  For
   example, if you wanted to override the configured kickoff time and have
   PKO kickoff at 8:45am, the command line would be:

      PKO /W /OT08:45

   Note that the override kickoff time parameter must come right after
   the switch; no spaces or colons (:) or equals signs (=) are allowed.
   Note also that the override kickoff time parameter must be in hh:mm
   format (ie, pad the hour with a leading "0" if necessary).  The
   override kickoff time must be in 24 hour format (see 5.10 above).

   A powerful feature of the override time switch is the ability to use "Hour
   Wildcards".  The Hour Wildcards are question marks that are used in place
   of the hour part of the override kickoff time.  When the wildcards are
   used, they instruct PKO to "substitute with the next hour".  For example,
   let's say that you execute the following command line at 3:30pm:


      PKO /W /OT??:15

   PKO will begin Wait Mode with kickoff scheduled for 4:15pm.  Using an
   override kickoff time and Hour Wildcards, you can configure PKO to
   back up your system all day long, at the top of the hour. First,
   change BACKUP.BAT to read:

      TNA2TAPE /A /Q
      PKO /W /OT??:00

   Next, initiate Wait Mode with:

      PKO /W /OT??:00

   PKO will start the backup at the top of each hour, until you suspend
   Wait Mode.

    5.52 Overriding the kickoff command

   The configured kickoff command may be overridden with the /OC switch.
   This switch requires a parameter: the override command itself.  For
   example, if you wanted to override the configured kickoff command
   with TNA2TAPE /A /Q, the command line would be:

      PKO /W /OC"TNA2TAPE /A /Q"

   Note that because the kickoff command contains embedded spaces, it
   must be enclosed in double quotes (").  The command must also be
   enclosed in double quotes if it contains forward slashes (/); this is
   necessary because otherwise, PKO would mistake the slashes for its
   own command line switches.  Our example above happens to contain both
   embedded spaces and forward slashes.  Here are some other examples:

      PKO /W /OCDO_BACKUP        (no need for quotes)
      PKO /W /OC"DO_BACKUP F:"   (embedded spaces, need quotes)
      PKO /W /OC"TNA2TAPE/A"     (no embedded spaces, but forward slash)

   Finally, note that the override kickoff command, like the kickoff command
   that is configured in Menu Mode, is limited to 14 characters.

    5.60 Running PKO with the Weekday Macro.

   The Weekday Macro allows you increased flexibility when you use PKO
   to kickoff a batch file.  The Weekday Macro is the percent sign (%),
   and to use it all you have to do is embed it somewhere in your
   kickoff command.  When PKO kicks off, it will "expand" the macro
   according to the current day:

      Sunday    = 1
      Monday    = 2
      Tuesday   = 3
      Wednesday = 4
      Thursday  = 5
      Friday    = 6
      Saturday  = 7

   There are a couple ways to use the Weekday Macro with batch files.
   First, you can use it to provide a parameter to your batch file.  For

   example, let's say you configure your kickoff command to be:

      BACKUP %

   Your batch file, BACKUP.BAT, would receive the current day via
   parameter 1 (which is referenced as %1 within the batch file), and
   would need to evaluate it, something like this:

   REM
   REM   Evaluate day & branch accordingly.
   REM
         IF "%1" == "1" goto SUN
         IF "%1" == "2" goto MON
         IF "%1" == "3" goto TUE
         IF "%1" == "4" goto WED
         IF "%1" == "5" goto THU
         IF "%1" == "6" goto FRI
         IF "%1" == "7" goto SAT
   :SAT
   :SUN
   REM
   REM   Don't run on the weekends.
   REM
         GOTO DONE
   :MON
   :TUE
   :WED
   :THU
   REM
   REM   Do automatic archiving during the week.
   REM
         TNA2TAPE /A /Q
         GOTO DONE
   :FRI
   REM
   REM   Do a full checkpoint on Friday
   REM
         TNA2TAPE /FC /Q
         GOTO DONE
   :DONE
         PKO/W

   This example doesn't have much basis in reality, but it should give
   you an idea how you can use the Weekday Macro as a parameter.

   A second way to use the Weekday Macro is by having a different batch
   file for each day of the week.  With this method, the macro is not a
   parameter, but a part of the batch file's name.  For example, let's
   say you configure your kickoff command to be:

      BACKUP%

   Then, you'd have 7 separate batch files, named BACKUP1.BAT,
   BACKUP2.BAT, BACKUP3.BAT, etc.  In keeping with the above example,
   here's what the batch files might look like:

   BACKUP1.BAT & BACKUP7.BAT
   -------------------------
   REM

   REM   Don't run on the weekends.
   REM
         PKO/W

   BACKUP2.BAT through BACKUP5.BAT
   -------------------------------
   REM
   REM   Do automatic archiving during the week.
   REM
         TNA2TAPE /A /Q
         PKO/W

   BACKUP6.BAT
   -----------
   REM
   REM   Do a full checkpoint on Friday
   REM
         TNA2TAPE /FC /Q
         PKO/W

   Note that when using this method, PKO will issue a warning when
   beginning Wait Mode because it won't be able to verify the existence
   of the kickoff command.  That is, because of the Weekday Macro, the
   exact kickoff command can't be known until kickoff time, so PKO won't
   be able to find it when it does its initial check at the beginning of
   Wait Mode.  You can disregard this warning.

   You can choose to use either method.  I myself prefer the first, as
   it keeps all the commands in one place, which makes for easier
   maintenance.  It also provides better readability. Apart from that,
   either method will function just fine; it's just a matter of your own
   preference.

    6.00 Notes

   As previously mentioned, PKO operates by "stuffing" your command into
   the computer's keyboard buffer.  PKO expects the keyboard buffer to
   be in the standard location: 0040:001Eh.  This should be true unless
   you are using a keyboard buffer device driver to expand the buffer
   size (the default size is 15 bytes, and device drivers are available
   to expand this size).  If so, you'll need to test PKO thoroughly and
   if necessary, remove the device driver.  I speak from experience!  I
   was using such a device driver, and PKO seemed to work just fine.
   Then, from the DOS prompt, I pressed a key and my monitor displayed a
   kaleidoscope of colors!

   If you happen to forget your password, don't despair.  Simply delete
   PKO.CFG.  You'll then have to reconfigure PKO as in 5.10, above.  At
   this point in PKO's development, this is not a problem, as the
   configuration file contains only a few items of data.

    7.00 Registration

   PKO is Shareware.  What is Shareware?  Shareware is simply an
   alternate method of marketing and distribution.  With Shareware, you
   get to "test drive" a program before you buy.  If you continue to use
   a Shareware program after a reasonable amount of time (say, a couple
   or weeks or so for PKO), you're expected to register it.


   The registration fee for PKO is $15.00.  To register, fill out the
   registration form (see the file, REGISTER.DOC) and mail it to me
   along with your payment of $15.00.  Upon receipt of your
   registration, I will send you the current version of PKO, unless you
   already have the current version.  In that case, I will still
   acknowledge your registration, and send you the next version when it
   is available.

    8.00 Distribution

   You are encouraged to distribute PKO in any manner; this is a basic
   principle of Shareware.  You may not charge a fee for your
   distribution; however, a nominal duplication or shipping and
   handling fee of no more than $3.00 is allowed.

   You must distribute the entire PKO package.  That is, all files
   included in the ZIP file as specified in 2.00 above.

    9.00 Support

   The best way to reach me is via CompuServe Mail.  My account is
   71760,2565.  Alternately, you may drop me a line:

        Darryl G. Whitmore
        48 West Fern Court
        Palatine, IL  60067-1402

   You may also contact me for support and help during the "test drive"
   phase.

   PKO has had over a year of use in "the field" without any reported
   hardware or software incompatibilties.  If you register PKO and
   subsequently encounter compatibility problems (or others, for that
   matter) that I can't resolve, I'll gladly refund of your
   registration.

   10.00 The "to do" list

   I have in mind a number of enhancements to PKO, among them:

      - A facility for viewing PKO.LOG from within Menu Mode.
      - Automatic purging of PKO.LOG when it reaches a certain size
        or age.
      - Enhanced kickoff configuration, such as:
         - different commands for different days of the week
         - kickoff after a certain length of time, rather than
           only at a certain time
         - configurable parameters that may be passed to the
           kickoff command
      - A command line override to make PKO kickoff _after_ a certain
        length of time.  For example, /OA04:00 to kickoff 4 hours
        after Wait Mode is initiated.

   Past PKO enhancements have been based on users' feature requests, and
   no doubt future enhancements will be, also. I welcome suggestions or
   comments.  Please feel free to contact me as outlined in 9.00, above.